home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_ddd.idb / usr / freeware / info / ddd.info-1.z / ddd.info-1
Text File  |  2001-10-09  |  40KB  |  1,201 lines
  1. This is ddd.info, produced by makeinfo version 4.0 from ddd.texi.
  2.  
  3. INFO-DIR-SECTION Miscellaneous
  4. START-INFO-DIR-ENTRY
  5. * DDD: (ddd).                     The Data Display Debugger.
  6. END-INFO-DIR-ENTRY
  7.  
  8. DDD is a graphical front-end for GDB and other command-line debuggers.
  9.  
  10. This is the First Edition, 2001-02-01, of `Debugging with DDD' for DDD
  11. Version 3.3.1.
  12.  
  13. Copyright (C) 2001 UniversitΣt Passau
  14. Lehrstuhl fⁿr Software-Systeme
  15. Innstra▀e 33
  16. D-94032 Passau
  17. GERMANY
  18.  
  19. Distributed by
  20. Free Software Foundation, Inc.
  21. 59 Temple Place - Suite 330
  22. Boston, MA 02111-1307
  23. USA
  24.  
  25. DDD and this manual are available via the DDD WWW page
  26. (http://www.gnu.org/software/ddd/).
  27.  
  28.    Permission is granted to copy, distribute and/or modify this document
  29. under the terms of the GNU Free Documentation License, Version 1.1 or
  30. any later version published by the Free Software Foundation; with no
  31. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
  32. copy of the license is included in the section entitled "GNU Free
  33. Documentation License".
  34.  
  35.    Send questions, comments, suggestions, etc. to <ddd@gnu.org>.
  36. Send bug reports to <bug-ddd@gnu.org>.
  37. 
  38. File: ddd.info,  Node: Top,  Next: Summary,  Up: (dir)
  39.  
  40. Debugging with DDD
  41. ******************
  42.  
  43.    DDD is a graphical front-end for GDB and other command-line
  44. debuggers.
  45.  
  46.    This is the First Edition of `Debugging with DDD', 2001-02-01, for
  47. DDD Version 3.3.1.
  48.  
  49.    The first part of this master menu lists the major nodes in this Info
  50. document, including the label and command indices.  The rest of the menu
  51. lists all the lower level nodes in the document.
  52.  
  53. * Menu:
  54.  
  55. * Summary::                     Summary of DDD.
  56.  
  57. * Sample Session::              A sample DDD session.
  58. * Invocation::                  Getting in and out of DDD.
  59. * Windows::                     The DDD windows, menus, and buttons.
  60. * Navigating::                  Moving through the source code.
  61. * Stopping::                    Making your program stop at specific locations.
  62. * Running::                     Running programs under DDD.
  63. * Examining Data::              Examining variable values and data structures.
  64. * Machine-Level Debugging::     Examining machine code and registers.
  65. * Changing the Program::        Changing source and object code.
  66. * Commands::                    Entering and editing DDD commands.
  67.  
  68. * Application Defaults::        Resources used in DDD.
  69. * Bugs::                        How, when, and why to report DDD bugs.
  70. * Configuration Notes::         Configuration-specific notes.
  71. * Dirty Tricks::                Room for your contributions.
  72. * Extending::                   Extending DDD.
  73. * FAQ::                         Frequently Answered Questions.
  74. * License::                     The DDD license.
  75. * Help and Assistance::         Mailing Lists and other resources.
  76. * Documentation License::       The license of this document.
  77.  
  78. * Label Index::                 All labels shown on the DDD GUI.
  79. * Key Index::                   Keys used to control DDD.
  80. * Command Index::               Commands that can be typed within DDD.
  81. * Resource Index::              All resources and environment variables.
  82. * File Index::                  All programs and files referenced by DDD.
  83. * Concept Index::               All concepts as mentioned in this manual.
  84.  
  85.  
  86.  
  87.  --- The Detailed Node Listing ---
  88.  
  89. Summary of DDD
  90.  
  91. * About this Manual::           Getting copies in various formats.
  92. * Free Software::               How to copy and redistribute DDD.
  93. * Getting DDD::              How to obtain copies of DDD.
  94. * Contributors::                Who has done all this?
  95. * History::                     Old DDD versions.
  96.  
  97. A Sample DDD Session
  98.  
  99. * Sample Program::              Source `sample.c'
  100.  
  101. Getting In and Out of DDD
  102.  
  103. * Invoking::                    How to invoke DDD.
  104. * Quitting::                    How to quit DDD.
  105. * Sessions::                    Saving work across invocations.
  106. * Remote Debugging::            Running DDD on a different host.
  107. * Customizing Debugger Interaction::  How DDD and GDB communicate.
  108.  
  109. Invoking DDD
  110.  
  111. * Choosing an Inferior Debugger::  Which debugger to use?
  112. * Options::                     How to invoke DDD
  113. * X Options::                   Setting X properties
  114. * Inferior Debugger Options::   Customizing GDB, DBX, and so on
  115. * Multiple Instances::          Running multiple DDD instances
  116. * X Warnings::                  Turning off obnoxious warnings
  117.  
  118. Inferior Debugger Options
  119.  
  120. * GDB Options::
  121. * DBX and Ladebug Options::
  122. * XDB Options::
  123. * JDB Options::
  124. * PYDB Options::
  125. * Perl Options::
  126.  
  127. Persistent Sessions
  128.  
  129. * Saving Sessions::
  130. * Resuming Sessions::
  131. * Deleting Sessions::
  132. * Customizing Sessions::
  133.  
  134. Remote Debugging
  135.  
  136. * Remote Host::                 Running DDD on a Remote Host
  137. * Remote Debugger::             Using a Remote Inferior Debugger
  138. * Remote Program::              Debugging a Remote Program
  139.  
  140. Using DDD with a Remote Inferior Debugger
  141.  
  142. * Customizing Remote Debugging::
  143.  
  144. Customizing Interaction with the Inferior Debugger
  145.  
  146. * Debugger Invocation::
  147. * Debugger Initialization::
  148. * Debugger Communication::
  149.  
  150. Initializing the Inferior Debugger
  151.  
  152. * GDB Initialization::
  153. * DBX Initialization::
  154. * XDB Initialization::
  155. * JDB Initialization::
  156. * PYDB Initialization::
  157. * Perl Initialization::
  158. * Finding a Place to Start::
  159. * Opening the Selection::
  160.  
  161. The DDD Windows
  162.  
  163. * Menu Bar::                    All DDD pull-down menus.
  164. * Tool Bar::                    The DDD icon buttons.
  165. * Command Tool::                The floating command tool.
  166. * Getting Help::                What does this thing mean?
  167. * Undo and Redo::               Oops!
  168. * Customizing::                 You can customize DDD
  169.  
  170. The Menu Bar
  171.  
  172. * File Menu::                   Selecting programs and processes.
  173. * Edit Menu::                   Cut, copy, paste, and preferences.
  174. * View Menu::                   All DDD windows.
  175. * Program Menu::                Starting and stopping.
  176. * Commands Menu::               All DDD commands.
  177. * Status Menu::                 Examining the program status.
  178. * Source Menu::                 Navigating around.
  179. * Data Menu::                   Examining data.
  180. * Maintenance Menu::            Maintaining DDD.
  181. * Help Menu::                   Getting help.
  182. * Customizing the Menu Bar::    Alternate key bindings, etc.
  183.  
  184. Customizing the Menu Bar
  185.  
  186. * Auto-Raise Menus::
  187. * Customizing the Edit Menu::
  188.  
  189. The Tool Bar
  190.  
  191. * Customizing the Tool Bar::
  192.  
  193. The Command Tool
  194.  
  195. * Customizing the Command Tool::
  196. * Customizing Tool Position::
  197.  
  198. Customizing the Command Tool
  199.  
  200. * Disabling the Command Tool::
  201.  
  202. Command Tool Position
  203.  
  204. * Customizing Tool Decoration::
  205.  
  206. Customizing DDD
  207.  
  208. * How Customizing Works::
  209. * Customizing Help::
  210. * Customizing Undo::
  211. * Customizing Windows::
  212. * Debugger Settings::
  213.  
  214. How Customizing DDD Works
  215.  
  216. * Resources::
  217. * Changing Resources::
  218. * Saving Options::
  219.  
  220. Customizing DDD Help
  221.  
  222. * Button tips::                 Turning off tips.
  223. * Tip of the day::              Turning off the tip of the day.
  224. * Help Helpers::                Helper programs invoked by Help.
  225.  
  226. Customizing the DDD Windows
  227.  
  228. * Splash Screen::               Turning off the splash screen.
  229. * Window Layout::               Re-arranging windows.
  230. * Customizing Fonts::           Using alternate fonts.
  231. * Toggling Windows::            Turning off windows.
  232. * Text Fields::                 Popdown histories.
  233. * Icons::                       Iconifying DDD windows.
  234. * Adding Buttons::              Create your own button set.
  235. * More Customizations::
  236.  
  237. Navigating through the Code
  238.  
  239. * Compiling for Debugging::     Always use `-g' to compile.
  240. * Opening Files::               How to open a program for debugging.
  241. * Looking up Items::            Searching files and functions.
  242. * Customizing Source::          Arranging the source window.
  243.  
  244. Opening Files
  245.  
  246. * Opening Programs::            How to open a program for debugging.
  247. * Opening Core Dumps::          Analyze a previous crash.
  248. * Opening Source Files::        Open a source file of the program.
  249. * Filtering Files::             DDD only lists matching files.
  250.  
  251. Looking up Items
  252.  
  253. * Looking up Definitions::      Jump towards a specific item.
  254. * Textual Search::              Search within the current source.
  255. * Looking up Previous Locations::  Navigate back and forth.
  256. * Source Path::                 Make DDD know where to search.
  257.  
  258. Customizing the Source Window
  259.  
  260. * Customizing Glyphs::
  261. * Customizing Searching::
  262. * Customizing Source Appearance::
  263. * Customizing Source Scrolling::
  264. * Customizing Source Lookup::
  265. * Customizing File Filtering::
  266.  
  267. Stopping the Program
  268.  
  269. * Breakpoints::                 Stop at a certain point.
  270. * Watchpoints::                 Stop at a certain condition.
  271. * Interrupting::                Stop manually.
  272. * Stopping X Programs::         Take care of grabbed pointers!
  273.  
  274. Breakpoints
  275.  
  276. * Setting Breakpoints::
  277. * Deleting Breakpoints::
  278. * Disabling Breakpoints::
  279. * Temporary Breakpoints::
  280. * Editing Breakpoint Properties::
  281. * Breakpoint Conditions::
  282. * Breakpoint Ignore Counts::
  283. * Breakpoint Commands::
  284. * Moving and Copying Breakpoints::
  285. * Looking up Breakpoints::
  286. * Editing all Breakpoints::
  287. * Hardware-Assisted Breakpoints::
  288.  
  289. Watchpoints
  290.  
  291. * Setting Watchpoints::
  292. * Editing Watchpoint Properties::
  293. * Editing all Watchpoints::
  294. * Deleting Watchpoints::
  295.  
  296. Stopping X Programs
  297.  
  298. * Customizing Grab Checking::
  299.  
  300. Running the Program
  301.  
  302. * Starting Program Execution::
  303. * Using the Execution Window::
  304. * Attaching to a Process::
  305. * Program Stop::
  306. * Resuming Execution::
  307. * Continuing Somewhere Else::
  308. * Stack::
  309. * Undoing Program Execution::
  310. * Threads::
  311. * Signals::
  312. * Killing the Program::
  313.  
  314. Starting Program Execution
  315.  
  316. * Arguments::                   Your program's arguments.
  317. * Environment::                 Your program's environment.
  318. * Working Directory::           Your program's directory.
  319. * Input/Output::                Your program's I/O.
  320.  
  321. Using the Execution Window
  322.  
  323. * Customizing the Execution Window::
  324.  
  325. Attaching to a Running Process
  326.  
  327. * Customizing Attaching to Processes::
  328.  
  329. Examining the Stack
  330.  
  331. * Frames::                      Callers and callees.
  332. * Backtraces::                  And you may ask yourself, `how did I get here?'
  333. * Selecting a frame::           Moving up and down.
  334.  
  335. Examining Data
  336.  
  337. * Value Tips::                  Just move the pointer on a variable.
  338. * Printing Values::             Printing a value in the debugger console.
  339. * Displaying Values::           Displaying structures as graphs.
  340. * Plotting Values::             Displaying values as plots.
  341. * Examining Memory::            Low-level memory examination.
  342.  
  343. Displaying Complex Values in the Data Window
  344.  
  345. * Display Basics::              How to create, manipulate, and delete displays.
  346. * Arrays::                      Special functions for arrays.
  347. * Assignment::                  Setting variable values.
  348. * Examining Structures::        Dereferencing pointers and other references.
  349. * Customizing Displays::        Data Themes.
  350. * Layouting the Graph::         Automatic layout.
  351. * Printing the Graph::          Printing on paper.
  352.  
  353. Display Basics
  354.  
  355. * Creating Single Displays::
  356. * Selecting Displays::
  357. * Showing and Hiding Details::
  358. * Rotating Displays::
  359. * Displaying Local Variables::
  360. * Displaying Program Status::
  361. * Refreshing the Data Window::
  362. * Placement::
  363. * Clustering::
  364. * Creating Multiple Displays::
  365. * Editing all Displays::
  366. * Deleting Displays::
  367.  
  368. Arrays
  369.  
  370. * Array Slices::                Displaying FROM..TO parts of an array
  371. * Repeated Values::             How repeated values are handled.
  372. * Arrays as Tables::            Displaying two-dimensional arrays.
  373.  
  374. Examining Structures
  375.  
  376. * Dependent Values::            Edges from values to values.
  377. * Dereferencing Pointers::      Examining pointer-based data structures.
  378. * Shared Structures::           Multiple pointers to one display.
  379. * Display Shortcuts::           Customize your own menus.
  380.  
  381. Customizing Displays
  382.  
  383. * Using Data Themes::
  384. * Applying Data Themes to Several Values::
  385. * Editing Themes::
  386. * Writing Data Themes::
  387. * Display Resources::
  388. * VSL Resources::
  389.  
  390. Layouting the Graph
  391.  
  392. * Moving Displays::
  393. * Scrolling Data::
  394. * Aligning Displays::
  395. * Automatic Layout::
  396. * Rotating the Graph::
  397.  
  398. Plotting Values
  399.  
  400. * Plotting Arrays::             Plotting 1-D and 2-D arrays.
  401. * Plot Appearance::             Controlling the appearance.
  402. * Scalars and Composites::      Plotting simple values.
  403. * Plotting Histories::          Plotting the history of a variable.
  404. * Printing Plots::              Printing on paper.
  405. * Entering Plotting Commands::  Raw Gnuplot commands.
  406. * Exporting Plot Data::         Processing data outside of DDD
  407. * Animating Plots::             Visualizing dynamic behaviour.
  408. * Customizing Plots::           All at your leisure.
  409.  
  410. Customizing Plots
  411.  
  412. * Gnuplot Invocation::
  413. * Gnuplot Settings::
  414.  
  415. Machine-Level Debugging
  416.  
  417. * Machine Code::                Examining machine code.
  418. * Machine Code Execution::      Stepping across instructions.
  419. * Registers::                   Examining registers.
  420. * Customizing Machine Code::    Settings.
  421.  
  422. Changing the Program
  423.  
  424. * Editing Source Code::         You can invoke a source editor from DDD.
  425. * Recompiling::                 Invoking `make' from within DDD.
  426. * Patching::                    Changing source and object code.
  427.  
  428. Editing Source Code
  429.  
  430. * Customizing Editing::
  431. * In-Place Editing::
  432.  
  433. The Command-Line Interface
  434.  
  435. * Entering Commands::           Direct interaction with the inferior debugger.
  436. * TTY mode::                    Controlling DDD from a terminal.
  437. * Integrating DDD::          DDD and your programming environment.
  438. * Defining Buttons::            Add your own DDD buttons.
  439. * Defining Commands::           Add your own DDD commands.
  440.  
  441. Entering Commands
  442.  
  443. * Command Completion::          Using the <TAB> key.
  444. * Command History::             Repeating previous commands.
  445. * Typing in the Source Window::
  446.  
  447. Defining Buttons
  448.  
  449. * Customizing Buttons::         Adding your own command buttons.
  450.  
  451. Defining Commands
  452.  
  453. * GDB Simple Commands::
  454. * GDB Argument Commands::
  455. * Commands with Other Debuggers::
  456.  
  457. Application Defaults
  458.  
  459. * Actions::                     All actions used in translation tables.
  460. * Images::                      All images used in resources,
  461.  
  462. Actions
  463.  
  464. * General Actions::
  465. * Data Display Actions::
  466. * Debugger Console Actions::
  467. * Source Window Actions::
  468.  
  469. Bugs and How To Report Them
  470.  
  471. * Where to Send Bug Reports::   Our e-mail address.
  472. * Is it a DDD Bug?::         DDD may not be at fault.
  473. * How to Report Bugs::          Report all the facts.
  474. * Bug Reports::                 Include all configuration information.
  475. * Diagnostics::                 Maintaining DDD
  476.  
  477. Getting Diagnostics
  478.  
  479. * Logging::                     DDD logs all interactions.
  480. * Debugging DDD::            Facilities to debug DDD.
  481. * Customizing Diagnostics::     All diagnostics resources.
  482.  
  483. Logging
  484.  
  485. * Disabling Logging::
  486.  
  487. Configuration Notes
  488.  
  489. * GDB::                         Using DDD with GDB
  490. * DBX::                         Using DDD with DBX
  491. * Ladebug::                     Using DDD with Ladebug
  492. * XDB::                         Using DDD with XDB
  493. * JDB::                         Using DDD with JDB
  494. * Perl::                        Using DDD with Perl
  495. * LessTif::                     Using DDD with LessTif
  496.  
  497. Using DDD with GDB
  498.  
  499. * WDB::                         Using DDD with WDB
  500. * WindRiver GDB::               Using DDD with WindRiver GDB (Tornado)
  501.  
  502. 
  503. File: ddd.info,  Node: Summary,  Next: Sample Session,  Prev: Top,  Up: Top
  504.  
  505. Summary of DDD
  506. **************
  507.  
  508.    The purpose of a debugger such as DDD is to allow you to see what is
  509. going on "inside" another program while it executes--or what another
  510. program was doing at the moment it crashed.
  511.  
  512.    DDD can do four main kinds of things (plus other things in support
  513. of these) to help you catch bugs in the act:
  514.  
  515.    * Start your program, specifying anything that might affect its
  516.      behavior.
  517.  
  518.    * Make your program stop on specified conditions.
  519.  
  520.    * Examine what has happened, when your program has stopped.
  521.  
  522.    * Change things in your program, so you can experiment with
  523.      correcting the effects of one bug and go on to learn about another.
  524.  
  525.    Technically speaking, DDD is a front-end to a command-line debugger
  526. (called "inferior debugger", because it lies at the layer beneath DDD).
  527. DDD supports the following inferior debuggers:
  528.  
  529.    * To debug _executable binaries_, you can use DDD with "GDB", "DBX",
  530.      "Ladebug", or "XDB".
  531.  
  532.         - "GDB", the GNU debugger, is the recommended inferior debugger
  533.           for DDD.  GDB supports native executables binaries originally
  534.           written in C, C++, Java, Modula-2, Modula-3, Pascal, Chill,
  535.           Ada, and FORTRAN.  (*note Using GDB with Different Languages:
  536.           (gdb)Languages., for information on language support in GDB.)
  537.  
  538.         - As an alternative to GDB, you can use DDD with the "DBX"
  539.           debugger, as found on several UNIX systems.  Most DBX
  540.           incarnations offer fewer features than GDB, and some of the
  541.           more advanced DBX features may not be supported by DDD.
  542.           However, using DBX may be useful if GDB does not understand
  543.           or fully support the debugging information as generated by
  544.           your compiler.
  545.  
  546.         - As an alternative to GDB and DBX, you can use DDD with
  547.           "Ladebug", as found on Compaq and DEC systems.  Ladebug
  548.           offers fewer features than GDB, and some of the more advanced
  549.           Ladebug features may not be supported by DDD.  However, using
  550.           Ladebug may be useful if GDB or DBX do not understand or
  551.           fully support the debugging information as generated by your
  552.           compiler.(1)
  553.  
  554.         - As another alternative to GDB, you can use DDD with the "XDB"
  555.           debugger, as found on HP-UX systems.(2).
  556.  
  557.    * To debug _Java byte code programs_, you can use DDD with "JDB",
  558.      the Java debugger, as of JDK 1.1 and later.  (DDD has been tested
  559.      with JDK 1.1 and JDK 1.2.)
  560.  
  561.    * To debug _Python programs_, you can use DDD with "PYDB", a Python
  562.      debugger.
  563.  
  564.    * To debug _Perl programs_, you can use DDD with the "Perl
  565.      debugger," as of Perl 5.003 and later.
  566.  
  567.    *Note Choosing an Inferior Debugger::, for choosing the appropriate
  568. inferior debugger.  *Note Sample Session::, for getting a first
  569. impression of DDD.
  570.  
  571. * Menu:
  572.  
  573. * About this Manual::           Getting copies in various formats.
  574. * Free Software::               How to copy and redistribute DDD.
  575. * Getting DDD::              How to obtain copies of DDD.
  576. * Contributors::                Who has done all this?
  577. * History::                     Old DDD versions.
  578.  
  579.    ---------- Footnotes ----------
  580.  
  581.    (1) Within DDD (and this manual), Ladebug is considered a DBX
  582. variant.  Hence, everything said for DBX also applies to Ladebug,
  583. unless stated otherwise.
  584.  
  585.    (2) XDB will no longer be maintained in future DDD releases.  Use a
  586. recent GDB version instead.
  587.  
  588. 
  589. File: ddd.info,  Node: About this Manual,  Next: Free Software,  Up: Summary
  590.  
  591. About this Manual
  592. =================
  593.  
  594.    This manual comes in several formats:
  595.  
  596.    * The _Info_ format is used for browsing on character devices; it
  597.      comes without pictures.  You should have a local copy installed,
  598.      which you can browse via Emacs, the stand-alone `info' program, or
  599.      from DDD via `Help => DDD Reference'.
  600.  
  601.      The DDD source distribution `ddd-3.3.1.tar.gz' contains this
  602.      manual as pre-formatted info files; you can also download them
  603.      from
  604.      the DDD WWW page (http://www.gnu.org/software/ddd/).
  605.  
  606.    * The _PostScript_ format is used for printing on paper; it comes
  607.      with pictures as well.
  608.  
  609.      The DDD source distribution `ddd-3.3.1.tar.gz' contains this
  610.      manual as pre-formatted PostScript file; you can also download it
  611.      from
  612.      the DDD WWW page (http://www.gnu.org/software/ddd/).
  613.  
  614.    * The _PDF_ format is used for printing on paper as well as for
  615.      online browsing; it comes with pictures as well.
  616.  
  617.      The DDD source distribution `ddd-3.3.1.tar.gz' contains this
  618.      manual as pre-formatted PDF file; you can also download it from
  619.      the DDD WWW page (http://www.gnu.org/software/ddd/).
  620.  
  621.    * The _HTML_ format is used for browsing on bitmap devices; it
  622.      includes several pictures.  You can view it using a HTML browser,
  623.      typically from a local copy.
  624.  
  625.      A pre-formatted HTML version of this manual comes in a separate
  626.      DDD package
  627.      `ddd-3.3.1-html-manual.tar.gz'; you can browse and download it via
  628.      the DDD WWW page (http://www.gnu.org/software/ddd/).
  629.  
  630.    The manual itself is written in TeXinfo format; its source code
  631. `ddd.texi' is contained in the DDD source distribution
  632. `ddd-3.3.1.tar.gz'.
  633.  
  634.    The picture sources come in a separate package
  635. `ddd-3.3.1-pics.tar.gz'; you need this package only if you want to
  636. re-create the PostScript, HTML, or PDF versions.
  637.  
  638. 
  639. File: ddd.info,  Node: Free Software,  Next: Getting DDD,  Prev: About this Manual,  Up: Summary
  640.  
  641. Free software
  642. =============
  643.  
  644.    DDD is "free"; this means that everyone is free to use it and free
  645. to redistribute it on a free basis.  DDD is not in the public domain;
  646. it is copyrighted and there are restrictions on its distribution, but
  647. these restrictions are designed to permit everything that a good
  648. cooperating citizen would want to do.  What is not allowed is to try to
  649. prevent others from further sharing any version of DDD that they might
  650. get from you.  The precise conditions are found in the GNU General
  651. Public License that comes with DDD; *Note License::, for details.
  652.  
  653.    The easiest way to get a copy of DDD is from someone else who has
  654. it.  You need not ask for permission to do so, or tell any one else;
  655. just copy it.
  656.  
  657. 
  658. File: ddd.info,  Node: Getting DDD,  Next: Contributors,  Prev: Free Software,  Up: Summary
  659.  
  660. Getting DDD
  661. ===========
  662.  
  663.    If you have access to the Internet, you can get the latest version of
  664. DDD from the anonymous FTP server `ftp.gnu.org' in the directory
  665. `/gnu/ddd'.  This should contain the following files:
  666.  
  667. ``ddd-VERSION.tar.gz''
  668.      The DDD source distribution.  This should be all you need.
  669.  
  670. ``ddd-VERSION-html-manual.tar.gz''
  671.      The DDD manual in HTML format.  You need this only if you want to
  672.      install a local copy of the DDD manual in HTML format.
  673.  
  674. ``ddd-VERSION-pics.tar.gz''
  675.      Sources of images included in the DDD manual.  You need this only
  676.      if you want to recreate the DDD manual.
  677.  
  678.    DDD can also be found at numerous other archive sites around the
  679. world; check the file `ANNOUNCE' in a DDD distribution for the latest
  680. known list.
  681.  
  682. 
  683. File: ddd.info,  Node: Contributors,  Next: History,  Prev: Getting DDD,  Up: Summary
  684.  
  685. Contributors to DDD
  686. ===================
  687.  
  688.    Dorothea Lⁿtkehaus and Andreas Zeller were the original authors of
  689. DDD.  Many others have contributed to its development.  The files
  690. `ChangeLog' and `THANKS' in the DDD distribution approximates a
  691. blow-by-blow account.
  692.  
  693. 
  694. File: ddd.info,  Node: History,  Prev: Contributors,  Up: Summary
  695.  
  696. History of DDD
  697. ==============
  698.  
  699.    The history of DDD is a story of code recycling.  The oldest parts of
  700. DDD were written in 1990, when _Andreas Zeller_ designed VSL, a
  701. box-based visual structure language for visualizing data and program
  702. structures.  The VSL interpreter and the Box library became part of
  703. Andreas' Diploma Thesis, a graphical syntax editor based on the
  704. Programming System Generator PSG.
  705.  
  706.    In 1992, the VSL and Box libraries were recycled for the NORA
  707. project.  For NORA, an experimental inference-based software
  708. development tool set, Andreas wrote a graph editor (based on VSL and
  709. the Box libraries) and facilities for inter-process knowledge exchange.
  710. Based on these tools, _Dorothea Lⁿtkehaus_ (now _Dorothea Krabiell_)
  711. realized DDD as her Diploma Thesis, 1994.
  712.  
  713.    The original DDD had no source window; this was added by Dorothea
  714. during the winter of 1994-1995.  In the first quarter of 1995, finally,
  715. Andreas completed DDD by adding command and execution windows,
  716. extensions for DBX and remote debugging as well as configuration
  717. support for several architectures.  Since then, Andreas has further
  718. maintained and extended DDD, based on the comments and suggestions of
  719. several DDD users around the world.  See the comments in the DDD source
  720. for details.
  721.  
  722.    Major DDD events:
  723.  
  724. April, 1995
  725.      DDD 0.9: First DDD beta release.
  726.  
  727. May, 1995
  728.      DDD 1.0: First public DDD release.
  729.  
  730. December, 1995
  731.      DDD 1.4: Machine-level debugging, glyphs, Emacs integration.
  732.  
  733. October, 1996
  734.      DDD 2.0: Color displays, XDB support, generic DBX support, command
  735.      tool.
  736.  
  737. May, 1997
  738.      DDD 2.1: Alias detection, button tips, status displays.
  739.  
  740. November, 1997
  741.      DDD 2.2: Sessions, display shortcuts.
  742.  
  743. June, 1998
  744.      DDD 3.0: Icon tool bar, Java support, JDB support.
  745.  
  746. December, 1998
  747.      DDD 3.1: Data plotting, Perl support, Python support, Undo/Redo.
  748.  
  749. January, 2000
  750.      DDD 3.2: New manual, Readline support, Ladebug support.
  751.  
  752. January, 2001
  753.      DDD 3.3: Data themes, JDB 1.2 support, VxWorks support.
  754.  
  755. 
  756. File: ddd.info,  Node: Sample Session,  Next: Invocation,  Prev: Summary,  Up: Top
  757.  
  758. A Sample DDD Session
  759. ********************
  760.  
  761.    You can use this manual at your leisure to read all about DDD.
  762. However, a handful of features are enough to get started using the
  763. debugger.  This chapter illustrates those features.
  764.  
  765.    The sample program `sample.c' (*note Sample Program::) exhibits the
  766. following bug.  Normally, `sample' should sort and print its arguments
  767. numerically, as in the following example:
  768.  
  769.      $ ./sample 8 7 5 4 1 3
  770.      1 3 4 5 7 8
  771.  
  772.    However, with certain arguments, this goes wrong:
  773.  
  774.      $ ./sample 8000 7000 5000 1000 4000
  775.      1000 1913 4000 5000 7000
  776.  
  777.    Although the output is sorted and contains the right number of
  778. arguments, some arguments are missing and replaced by bogus numbers;
  779. here, `8000' is missing and replaced by `1913'.(1)
  780.  
  781.    Let us use DDD to see what is going on.  First, you must compile
  782. `sample.c' for debugging (*note Compiling for Debugging::), giving the
  783. `-g' flag while compiling:
  784.  
  785.      $ gcc -g -o sample sample.c
  786.  
  787. * Menu:
  788.  
  789. * Sample Program::              Source `sample.c'
  790.  
  791.    Now, you can invoke DDD (*note Invocation::) on the `sample'
  792. executable:
  793.  
  794.      $ ddd sample
  795.  
  796.    After a few seconds, DDD comes up.  The "Source Window" contains the
  797. source of your debugged program; use the "Scroll Bar" to scroll through
  798. the file.
  799.  
  800.    The "Debugger Console" (at the bottom) contains DDD version
  801. information as well as a GDB prompt.(2)
  802.  
  803.      GNU DDD Version 3.3.1, by Dorothea Lⁿtkehaus and Andreas Zeller.
  804.      Copyright (C) 1999 Technische UniversitΣt Braunschweig, Germany.
  805.      Copyright (C) 2001 UniversitΣt Passau, Germany.
  806.      Reading symbols from sample...done.
  807.      (gdb)
  808.  
  809.    The first thing to do now is to place a "Breakpoint" (*note
  810. Breakpoints::), making `sample' stop at a location you are interested
  811. in.  Click on the blank space left to the initialization of `a'.  The
  812. "Argument field" `():' now contains the location (`sample.c:31').  Now,
  813. click on `Break' to create a breakpoint at the location in `()'.  You
  814. see a little red stop sign appear in line 31.
  815.  
  816.    The next thing to do is to actually "execute" the program, such that
  817. you can examine its behavior (*note Running::).  Select `Program =>
  818. Run' to execute the program; the `Run Program' dialog appears.
  819.  
  820.    In `Run with Arguments', you can now enter arguments for the
  821. `sample' program.  Enter the arguments resulting in erroneous behavior
  822. here--that is, `8000 7000 5000 1000 4000'.  Click on `Run' to start
  823. execution with the arguments you just entered.
  824.  
  825.    GDB now starts `sample'.  Execution stops after a few moments as the
  826. breakpoint is reached.  This is reported in the debugger console.
  827.  
  828.      (gdb) break sample.c:31
  829.      Breakpoint 1 at 0x8048666: file sample.c, line 31.
  830.      (gdb) run 8000 7000 5000 1000 4000
  831.      Starting program: sample 8000 7000 5000 1000 4000
  832.      
  833.      Breakpoint 1, main (argc=6, argv=0xbffff918) at sample.c:31
  834.      (gdb)
  835.  
  836.    The current execution line is indicated by a green arrow.
  837.  
  838.      => a = (int *)malloc((argc - 1) * sizeof(int));
  839.  
  840.    You can now examine the variable values.  To examine a simple
  841. variable, you can simply move the mouse pointer on its name and leave
  842. it there.  After a second, a small window with the variable value pops
  843. up (*note Value Tips::).  Try this with `argv' to see its value (`6').
  844. The local variable `a' is not yet initialized; you'll probably see
  845. `0x0' or some other invalid pointer value.
  846.  
  847.    To execute the current line, click on the `Next' button on the
  848. command tool.  The arrow advances to the following line.  Now, point
  849. again on `a' to see that the value has changed and that `a' has
  850. actually been initialized.
  851.  
  852.    To examine the individual values of the `a' array, enter `a[0]' in
  853. the argument field (you can clear it beforehand by clicking on `():')
  854. and then click on the `Print' button.  This prints the current value of
  855. `()' in the debugger console (*note Printing Values::).  In our case,
  856. you'll get
  857.  
  858.      (gdb) print a[0]
  859.      $1 = 0
  860.      (gdb)
  861.  
  862. or some other value (note that `a' has only been allocated, but the
  863. contents have not yet been initialized).
  864.  
  865.    To see all members of `a' at once, you must use a special GDB
  866. operator.  Since `a' has been allocated dynamically, GDB does not know
  867. its size; you must specify it explicitly using the `@' operator (*note
  868. Array Slices::).  Enter `a[0]@(argc - 1)' in the argument field and
  869. click on the `Print' button.  You get the first `argc - 1' elements of
  870. `a', or
  871.  
  872.      (gdb) print a[0]@(argc - 1)
  873.      $2 = {0, 0, 0, 0, 0}
  874.      (gdb)
  875.  
  876.    Rather than using `Print' at each stop to see the current value of
  877. `a', you can also "display" `a', such that its is automatically
  878. displayed.  With `a[0]@(argc - 1)' still being shown in the argument
  879. field, click on `Display'.  The contents of `a' are now shown in a new
  880. window, the "Data Window".  Click on `Rotate' to rotate the array
  881. horizontally.
  882.  
  883.    Now comes the assignment of `a''s members:
  884.  
  885.      =>  for (i = 0; i < argc - 1; i++)
  886.              a[i] = atoi(argv[i + 1]);
  887.  
  888.    You can now click on `Next' and `Next' again to see how the
  889. individual members of `a' are being assigned.  Changed members are
  890. highlighted.
  891.  
  892.    To resume execution of the loop, use the `Until' button.  This makes
  893. GDB execute the program until a line greater than the current is
  894. reached.  Click on `Until' until you end at the call of `shell_sort' in
  895.  
  896.      =>  shell_sort(a, argc);
  897.  
  898.    At this point, `a''s contents should be `8000 7000 5000 1000 4000'.
  899. Click again on `Next' to step over the call to `shell_sort'.  DDD ends
  900. in
  901.  
  902.      =>  for (i = 0; i < argc - 1; i++)
  903.              printf("%d ", a[i]);
  904.  
  905. and you see that after `shell_sort' has finished, the contents of `a'
  906. are `1000, 1913, 4000, 5000, 7000'--that is, `shell_sort' has somehow
  907. garbled the contents of `a'.
  908.  
  909.    To find out what has happened, execute the program once again.  This
  910. time, you do not skip through the initialization, but jump directly into
  911. the `shell_sort' call.  Delete the old breakpoint by selecting it and
  912. clicking on `Clear'.  Then, create a new breakpoint in line 35 before
  913. the call to `shell_sort'.  To execute the program once again, select
  914. `Program => Run Again'.
  915.  
  916.    Once more, DDD ends up before the call to `shell_sort':
  917.      =>  shell_sort(a, argc);
  918.  
  919.    This time, you want to examine closer what `shell_sort' is doing.
  920. Click on `Step' to step into the call to `shell_sort'.  This leaves
  921. your program in the first executable line, or
  922.  
  923.      => int h = 1;
  924.  
  925.    while the debugger console tells us the function just entered:
  926.  
  927.      (gdb) step
  928.      shell_sort (a=0x8049878, size=6) at sample.c:9
  929.      (gdb)
  930.  
  931.    This output that shows the function where `sample' is now suspended
  932. (and its arguments) is called a "stack frame display".  It shows a
  933. summary of the stack.  You can use `Status => Backtrace' to see where
  934. you are in the stack as a whole; selecting a line (or clicking on `Up'
  935. and `Down') will let you move through the stack.  Note how the `a'
  936. display disappears when its frame is left.
  937.  
  938.    Let us now check whether `shell_sort''s arguments are correct.
  939. After returning to the lowest frame, enter `a[0]@size' in the argument
  940. field and click on `Print':
  941.  
  942.      (gdb) print a[0] @ size
  943.      $4 = {8000, 7000, 5000, 1000, 4000, 1913}
  944.      (gdb)
  945.  
  946.    Surprise!  Where does this additional value `1913' come from?  The
  947. answer is simple: The array size as passed in `size' to `shell_sort' is
  948. _too large by one_--`1913' is a bogus value which happens to reside in
  949. memory after `a'.  And this last value is being sorted in as well.
  950.  
  951.    To see whether this is actually the problem cause, you can now assign
  952. the correct value to `size' (*note Assignment::).  Select `size' in the
  953. source code and click on `Set'.  A dialog pops up where you can edit
  954. the variable value.
  955.  
  956.    Change the value of `size' to `5' and click on `OK'.  Then, click on
  957. `Finish' to resume execution of the `shell_sort' function:
  958.  
  959.      (gdb) set variable size = 5
  960.      (gdb) finish
  961.      Run till exit from #0  shell_sort (a=0x8049878, size=5) at sample.c:9
  962.      0x80486ed in main (argc=6, argv=0xbffff918) at sample.c:35
  963.      (gdb)
  964.  
  965.    Success!  The `a' display now contains the correct values `1000,
  966. 4000, 5000, 7000, 8000'.
  967.  
  968.    You can verify that these values are actually printed to standard
  969. output by further executing the program.  Click on `Cont' to continue
  970. execution.
  971.  
  972.      (gdb) cont
  973.      1000 4000 5000 7000 8000
  974.      
  975.      Program exited normally.
  976.      (gdb)
  977.  
  978.    The message `Program exited normally.' is from GDB; it indicates
  979. that the `sample' program has finished executing.
  980.  
  981.    Having found the problem cause, you can now fix the source code.
  982. Click on `Edit' to edit `sample.c', and change the line
  983.  
  984.      shell_sort(a, argc);
  985.  
  986. to the correct invocation
  987.  
  988.      shell_sort(a, argc - 1);
  989.  
  990.    You can now recompile `sample'
  991.  
  992.      $ gcc -g -o sample sample.c
  993.  
  994. and verify (via `Program => Run Again') that `sample' works fine now.
  995.  
  996.      (gdb) run
  997.      `sample' has changed; re-reading symbols.
  998.      Reading in symbols...done.
  999.      Starting program: sample 8000 7000 5000 1000 4000
  1000.      1000 4000 5000 7000 8000
  1001.      
  1002.      Program exited normally.
  1003.      (gdb)
  1004.  
  1005.    All is done; the program works fine now.  You can end this DDD
  1006. session with `Program => Exit' or `Ctrl+Q'.
  1007.  
  1008.    ---------- Footnotes ----------
  1009.  
  1010.    (1) Actual numbers and behavior on your system may vary.
  1011.  
  1012.    (2) Re-invoke DDD with `--gdb', if you do not see a `(gdb)' prompt
  1013. here (*note Choosing an Inferior Debugger::)
  1014.  
  1015. 
  1016. File: ddd.info,  Node: Sample Program,  Up: Sample Session
  1017.  
  1018. Sample Program
  1019. ==============
  1020.  
  1021.    Here's the source `sample.c' of the sample program.
  1022.  
  1023.      /* sample.c -- Sample C program to be debugged with DDD */
  1024.      
  1025.      #include <stdio.h>
  1026.      #include <stdlib.h>
  1027.      
  1028.      static void shell_sort(int a[], int size)
  1029.      {
  1030.          int i, j;
  1031.          int h = 1;
  1032.          do {
  1033.              h = h * 3 + 1;
  1034.          } while (h <= size);
  1035.          do {
  1036.              h /= 3;
  1037.              for (i = h; i < size; i++)
  1038.              {
  1039.                  int v = a[i];
  1040.                  for (j = i; j >= h && a[j - h] > v; j -= h)
  1041.                      a[j] = a[j - h];
  1042.                  if (i != j)
  1043.                      a[j] = v;
  1044.              }
  1045.          } while (h != 1);
  1046.      }
  1047.      
  1048.      int main(int argc, char *argv[])
  1049.      {
  1050.          int *a;
  1051.          int i;
  1052.      
  1053.          a = (int *)malloc((argc - 1) * sizeof(int));
  1054.          for (i = 0; i < argc - 1; i++)
  1055.              a[i] = atoi(argv[i + 1]);
  1056.      
  1057.          shell_sort(a, argc);
  1058.      
  1059.          for (i = 0; i < argc - 1; i++)
  1060.              printf("%d ", a[i]);
  1061.          printf("\n");
  1062.      
  1063.          free(a);
  1064.          return 0;
  1065.      }
  1066.  
  1067. 
  1068. File: ddd.info,  Node: Invocation,  Next: Windows,  Prev: Sample Session,  Up: Top
  1069.  
  1070. Getting In and Out of DDD
  1071. *************************
  1072.  
  1073. This chapter discusses how to start DDD, and how to get out of it.  The
  1074. essentials are:
  1075.  
  1076.    * Type `ddd' to start DDD (*note Invoking::).
  1077.  
  1078.    * Use `File => Exit' or `Ctrl+Q' to exit (*note Quitting::).
  1079.  
  1080. * Menu:
  1081.  
  1082. * Invoking::                    How to invoke DDD.
  1083. * Quitting::                    How to quit DDD.
  1084. * Sessions::                    Saving work across invocations.
  1085. * Remote Debugging::            Running DDD on a different host.
  1086. * Customizing Debugger Interaction::  How DDD and GDB communicate.
  1087.  
  1088. 
  1089. File: ddd.info,  Node: Invoking,  Next: Quitting,  Up: Invocation
  1090.  
  1091. Invoking DDD
  1092. ============
  1093.  
  1094.    Normally, you can run DDD by invoking the program `ddd'.
  1095.  
  1096.    You can also run DDD with a variety of arguments and options, to
  1097. specify more of your debugging environment at the outset.
  1098.  
  1099.    The most usual way to start DDD is with one argument, specifying an
  1100. executable program:
  1101.  
  1102.      ddd PROGRAM
  1103.  
  1104. If you use GDB, DBX, Ladebug, or XDB as inferior debuggers, you can also
  1105. start with both an executable program and a core file specified:
  1106.  
  1107.      ddd PROGRAM CORE
  1108.  
  1109.    You can, instead, specify a process ID as a second argument, if you
  1110. want to debug a running process:
  1111.  
  1112.      ddd PROGRAM 1234
  1113.  
  1114. would attach DDD to process `1234' (unless you also have a file named
  1115. `1234'; DDD does check for a core file first).
  1116.  
  1117.    You can further control DDD by invoking it with specific "options".
  1118. To get a list of DDD options, invoke DDD as
  1119.  
  1120.      ddd --help
  1121.  
  1122.    Most important are the options to specify the inferior debugger
  1123. (*note Choosing an Inferior Debugger::), but you can also customize
  1124. several aspects of DDD upon invocation (*note Options::).
  1125.  
  1126.    DDD also understands the usual X options such as `-display' or
  1127. `-geometry'.  *Note X Options::, for details.
  1128.  
  1129.    All arguments and options that are not understood by DDD are passed
  1130. to the inferior debugger; *Note Inferior Debugger Options::, for a
  1131. survey.  To pass an option to the inferior debugger that conflicts with
  1132. an X option, or with a DDD option listed here, use the `--debugger'
  1133. option (*note Options::).
  1134.  
  1135. * Menu:
  1136.  
  1137. * Choosing an Inferior Debugger::  Which debugger to use?
  1138. * Options::                     How to invoke DDD
  1139. * X Options::                   Setting X properties
  1140. * Inferior Debugger Options::   Customizing GDB, DBX, and so on
  1141. * Multiple Instances::          Running multiple DDD instances
  1142. * X Warnings::                  Turning off obnoxious warnings
  1143.  
  1144. 
  1145. File: ddd.info,  Node: Choosing an Inferior Debugger,  Next: Options,  Up: Invoking
  1146.  
  1147. Choosing an Inferior Debugger
  1148. -----------------------------
  1149.  
  1150.    The most frequently required options are those to choose a specific
  1151. inferior debugger.
  1152.  
  1153.    Normally, the inferior debugger is determined by the program to
  1154. analyze:
  1155.  
  1156.    * If the program requires a specific interpreter, such as Java,
  1157.      Python, or Perl, then you should use a JDB, PYDB, or Perl inferior
  1158.      debugger.
  1159.  
  1160.      Use
  1161.  
  1162.           ddd --jdb PROGRAM
  1163.  
  1164.           ddd --pydb PROGRAM
  1165.  
  1166.           ddd --perl PROGRAM
  1167.  
  1168.      to run DDD with JDB, PYDB, or Perl as inferior debugger.
  1169.  
  1170.    * If the program is an executable binary, you should use GDB, DBX,
  1171.      Ladebug, or XDB.  In general, GDB (or its HP variant, WDB)
  1172.      provides the most functionality of these debuggers.
  1173.  
  1174.      Use
  1175.  
  1176.           ddd --gdb PROGRAM
  1177.  
  1178.           ddd --wdb PROGRAM
  1179.  
  1180.           ddd --dbx PROGRAM
  1181.  
  1182.           ddd --ladebug PROGRAM
  1183.  
  1184.           ddd --xdb PROGRAM
  1185.  
  1186.      to run DDD with GDB, WDB, DBX, Ladebug, or XDB as inferior
  1187.      debugger.
  1188.  
  1189.    If you invoke DDD without any of these options, but give a PROGRAM
  1190. to analyze, then DDD will automatically determine the inferior debugger:
  1191.  
  1192.    * If PROGRAM is a Python program, a Perl script, or a Java class,
  1193.      DDD will invoke the appropriate debugger.
  1194.  
  1195.    * If PROGRAM is an executable binary, DDD will invoke its default
  1196.      debugger for executables (usually GDB).
  1197.  
  1198.    *Note Customizing Debugger Interaction::, for more details on
  1199. determining the inferior debugger.
  1200.  
  1201.